<html>
<body>
<h1>Maven Plugin</h1>

<p>
    The Maven plugin allows importing and verification of artifacts from Maven repositories.
</p>

<div id="import">
    <p>Importing will import one or more artifacts from a Maven repository, automatically importing
    the runtime path, including any transitive and optional dependencies.</p>
    <p>The import target requires that you have Maven installed as it uses a custom Maven
        plugin to extract the dependency information of artifacts stored in Maven repositories.</p>

    <p>Importing also requires that a mapping is defined between the Maven id and it's
        quokka counterpart. There is a global set of mappings stored in the quokka repository
        that is downloaded automatically. This is merged will any mappings defined locally (the default
        location is mappings.xml in your preferences directory).
    </p>

    <p>This global mappings will probably suffice if you are importing a new
        version of an already existing artifact. However, if you are importing something new to the repository,
        you will need to define your own mappings. Following is a sample mapping file:</p>
    <pre>&lt;mappings&gt;
    &lt;id-mappings&gt;
        &lt;!-- From maven id "groupId:artifactId::classifier:version" to quokka "group:name::version" --&gt;
        &lt;id-mapping from="org.mortbay.jetty:jetty" to="mortbay.jetty"/&gt;
        &lt;id-mapping from="org.mortbay.jetty:jetty-util" to="mortbay.jetty:util"/&gt;
        &lt;id-mapping from="org.mortbay.jetty:jetty-plus" to="mortbay.jetty:plus"/&gt;
        &lt;id-mapping from="bsf:bsf" to="apache.bsf"/&gt;
        &lt;id-mapping from="log4j:log4j" to="apache.log4j"/&gt;
        &lt;id-mapping from="asm:asm" to="ow2.asm"/&gt;
        &lt;id-mapping from="cobertura:cobertura" to="sf.cobertura"/&gt;
        &lt;id-mapping from="org.apache.ant:ant-antlr" to="apache.ant:antlr"/&gt;
        &lt;id-mapping from="org.apache.ant:ant-apache-bcel" to="apache.ant:bcel"/&gt;
        &lt;id-mapping from="org.apache.ant:ant-apache-bsf" to="apache.ant:bsf"/&gt;
    &lt;/id-mappings&gt;
    &lt;type-mappings&gt;
        &lt;!-- Mappings from maven types to quokka types. If the types match, no mapping is needed --&gt;
        &lt;type-mapping from="pom" to="paths"/&gt;
    &lt;/type-mappings&gt;
    &lt;license-mappings&gt;
        &lt;!-- These are mappings between maven license names and quokka license artifacts --&gt;
        &lt;license-mapping from="The Apache Software License, Version 2.0" to-group="license.apache" to-version="2.0"/&gt;
        &lt;license-mapping from="Apache License Version 2.0" to-group="license.apache" to-version="2.0"/&gt;
    &lt;/license-mappings&gt;
&lt;/mappings&gt;
</pre>
<p><b>Mapping notes:</b></p>
    <ul>
        <li style="list-style:square">There can be many Maven ids mapped to a single quokka id. e.g.
        the Maven ids <tt>ant:ant</tt> and <tt>org.apache.ant:ant</tt> both map to the quokka id of
        <tt>apache.ant:ant</tt></li>
        <li style="list-style:square">The mappings do not have to contain the same number of tokens
        on each side of the mapping. e.g. <tt>cobertura:cobertura</tt> with groupId and artifactId tokens
        maps to the single quokka group token of <tt>sf.cobertura</tt></li>
        <li style="list-style:square">The most specific mapping wins if there are multiple possible mappings
        that match. When searching for a mapping, the import target looks for a match on <tt>groupId:artifactId::classifier:version</tt>
        then <tt>groupId:artifactId::classifier</tt>, then <tt>groupId:artifactId</tt></li>
    </ul>
    <p>If you intend to upload to the global quokka repository, make sure you've read the <a href="">Upload Guide</a>
    and followed the instructions, particularly regarding naming standards.</p>

    <p><b>Properties:</b></p>

    <p>All properties are optional unless stated otherwise.</p>
    <ul>
        <li><b>repository</b>: The name of the repository to install the imported artifact into. Defaults
            to the project's repository.
        </li>
        <li><b>ids or id</b>: Either <tt>ids</tt> or <tt>id</tt> must be specified. <tt>id</tt> is a Maven id in the
            format <tt>groupId:artifactId:type:classifier:version</tt>. <tt>ids</tt> refers
            to a file containing a list of maven ids in the same format as <tt>id</tt>.
            The file may contain blank lines and any line starting with <tt>#</tt> is ignored. Both
            properties may be specified on the command. e.g. <tt>quokka maven:import -Did=ant:ant-launcher:jar::1.6.5</tt>
        </li>
        <li><b>template</b>: The maven project file that quokka uses to extract dependencies. Any occurences
            of <tt>@pluginVersion@</tt> are replaced by the value of the <tt>pluginVersion</tt> property. By default, it uses
            an in-built template. Defaults to the latest plugin version available when the maven plugin was built.
        </li>
        <li><b>mvn</b>: Path of the mvn command. Caution, you should use Maven versions >= 2.0.8 as apparently
            prior versions can return invalid results. Defaults to <tt>mvn</tt>.
        </li>
        <li><b>force</b>: True or false. If true, the artifact will be installed even if there are inconsistencies
            between the paths of the imported artifact and the maven version. Defaults to false.
        </li>
        <li><b>localMappings</b>: A file containing local id mappings as described above.
        </li>
        <li><b>remoteMappings</b>: The location of the remote mappings file
        </li>
        <li><b>cache</b>: The location where remote mappings will be cached locally until they expire
        </li>
        <li><b>cacheExpiry</b>: The number of seconds until the remote mappings should be downloaded again to
            refresh the cache.
        </li>
    </ul>
</div>
<div id="verify">
    <p>Although the verify target is part of the Maven plugin, it can be used for repositories that
    have not been imported from maven. In fact, the vast majority of verification checks performed
    are nothing to do with maven.</p>
    <p>Verify is a bit like lint in that it reports not only things that are errors, but
    warns about things that are suspicious. If a warning turns out to be a false positive, it
    should be added to the verified issues file so that it is not reported again.</p>
    <p>At present the following checks are performed:</p>
    <div class="indent">
    <ul>
        <li style="list-style:square">Checks the artifact has a license</li>
        <li style="list-style:square">Warns if the artifact has multiple licenses</li>
        <li style="list-style:square">Checks the version is in a standard format</li>
        <li style="list-style:square">Warns if the name and group do not match conventions</li>
        <li style="list-style:square">Checks there is a description</li>
        <li style="list-style:square">Checks there are no duplicates by hash or maven id</li>
        <li style="list-style:square">Checks there are no mandatory dependencies on certain libraries such as XML apis</li>
        <li style="list-style:square">Checks that the description, licenses, dependencies and paths match the previous version of the same artifact</li>
        <li style="list-style:square">Warns if the aritfact does not exist in the maven repository</li>
        <li style="list-style:square">If the artifact exists in maven, checks that the paths and checksums match</li>
        <li style="list-style:square">Checks that any referenced artifacts including dependencies, conflicts and overrides exist in the repository</li>
        <li style="list-style:square">Checks that stubs don't have artifacts</li>
        <li style="list-style:square">Checks that artifacts don't exist in parent repositories</li>
        <li style="list-style:square">Checks that artifacts that are grouped together have the same version</li>
    </ul>
    </div>

    <p><b>Properties:</b></p>

    <p>All properties are optional unless stated otherwise.</p>
    <ul>
        <li><b>repository</b>: Mandatory. The name of the repository to verify.
        </li>
        <li><b>ids or id</b>: See the import target for more information. In the case of verify however,
            these properties are optional and are used to limit which ids are verified.
        </li>
        <li><b>localVerifiedIssues</b>: A file containing local verified issues. The verified issues file
            is a text file containing regular expressions of warnings to ignore. Blank lines and
            those starting with <tt>#</tt> are ignored. Line content after <tt>//</tt> is also ignored.
            The following is an example of some verified issues:
            <pre>Duplicate hashes: apache.xerces:xml-apis:jar:2.6, apache.xerces:xml-apis:jar:2.6.2
Maven and quokka runtime paths do not match: apache\.fop:fop:jar:0\.20\.5.* // Removed mandatory dependencies on XML libs
</pre>
        </li>
        <li><b>remoteVerifiedIssues</b>: The location of the remote verified issues file
        </li>
        <li><b>failOnWarnings</b>: If true (the default), warnings will result in the build failing
        </li>
        <li><b>compareMavenHash</b>: If true, the hash of the artifacts will be compared to the hash
            in the maven repository. This is slow and is therefore disabled by default.
        </li>
        <li><b>compareMavenPaths</b>: If true, the runtime path dependencies will be compared to the
            Maven equivalent. This is very slow (~ 3s/check) and is therefore disabled by default.
        </li>
        <li><b>commonRoots</b>: Group prefixes that are irrelevant in determining if 2 artifacts are related or not.
            e.g. Because 2 artifacts both start with <tt>sf.</tt> doesn't mean the artifacts are related.
        </li>
        <li><b>template, mvn, cache &amp; cacheExpiry, localMappings, remoteMappings</b>: See the import target above for more information.
        </li>
    </ul>
</div>
</body>
</html>